The Very Best of Atari Inside

home *** CD-ROM | disk | FTP | other *** search

/ The Very Best of Atari Inside / The Very Best of Atari Inside 1.iso / mint / mnthlp95 / source / p.src < prev next >

Wrap

Text File | 1992-08-04 | 41KB | 1,127 lines

screen(capsensitive("Pause")) NAME Pause - suspend process until a signal is received SYNOPSIS void Pause(void); DESCRIPTION Pause causes the calling process to go to sleep until a sig- nal that is not being ignored or masked is received. If a signal handler has been established for that signal with the \#Psignal\# system call, then the handler is invoked before Pause returns; if the handler does a longjmp to a different point in the program, if it exits the program, or if the signal handler was set to SIG_DFL and the default action for the signal is to terminate the process, then Pause will never return. SEE ALSO \#Psigblock\#, \#Psignal\#, \#Psigpause\#, \#Psigsetmask\# Last change: May 1, 1991\end screen(capsensitive("Pdomain")) NAME Pdomain - get or set process execution domain SYNOPSIS WORD Pdomain(WORD dom); DESCRIPTION Pdomain gets or sets the process execution domain. This is a number which controls the behavior of a process. The default domain is 0, which is the TOS compatibility domain and in which all system calls behave exactly as they do under TOS. Domain 1 is the MiNT domain; in this domain, the behavior of the \#Fread\# and \#Fwrite\# system calls when applied to terminals are controlled by the current terminal settings as esta- blished by the \#Fcntl\# system call. Moreover, file names returned from \#Fsfirst\# and \#Fsnext\# may be treated differently; MiNT domain processes are expected to be able to deal with file names that are not standard 8 character name + 3 char- acter extension, all upper case, DOS file names. If dom is greater than or equal to 0, the process domain is set to its value. Note that only domains 0 and 1 are currently defined, and the result of using a different (positive) number for dom is unpredictable. If dom is nega- tive, no change is made to the process domain. RETURNS The process domain at the time of the Pdomain call (i.e. before any change). Last change: Oct. 1, 1991\end screen(capsensitive("Pfork")) NAME Pfork - create a copy of the current process SYNOPSIS WORD Pfork(void); DESCRIPTION Pfork creates a copy of the current process. The child (the new process created) inherits a copy of the parent's address space, not the parent's original memory, and so changes to variables in the child do not affect the parent in any way. The new process begins execution with an apparent return from the Pfork call. RETURNS 0 in the child The new process id (a positive number), in the parent. ENSMEM if there is not enough memory to create the new pro- cess. SEE ALSO \#Pexec\#, \#Pvfork\# BUGS If the parent is in supervisor mode when this call is made, the child will be started in user mode anyway; thus, it is strongly recommended that this call be made only from user mode. The current implementation of Pfork acts like Pvfork in that the parent is suspended until the child either exits or overlays itself with Pexec mode 200. Do not rely on this behavior, as it will be changed in future versions of MiNT. Last change: Oct. 1, 1991\end screen(capsensitive("Pgetuid"),capsensitive("Pgetgid"), capsensitive("Pgeteuid"),capsensitive("Pgetegid")) NAME Pgetuid, Pgetgid - get the current user or group id SYNOPSIS WORD Pgetuid(void); WORD Pgetgid(void); WORD Pgeteuid(void); WORD Pgetegid(void); DESCRIPTION Pgetuid returns the user id of the currently running pro- cess. This is a number between 0 and 255 which determines the access permissions of the process, and which may be used in multi-user systems to distinguish different users of the system. Similarly, Pgetgid returns the group id of the currently running process; this will also be a number between 0 and 255. Pgeteuid and Pgetegid are similar to Pgetuid and Pgetgid respectively, except that they return the effective user or group id. This is normally the same as the real user or group id, except that if a program is run which has the set uid or set gid bit set, it will run with an effective user or group id equal to the owner of the program file. Access to files is based upon the effective user or group id, so the set uid (and set gid) mechanism allows users (in particular the super user) to grant permissions to other users. This mechanism also exists in the Unix(tm) operating system. SEE ALSO \#Psetuid\# Last change: Aug. 1, 1992\end screen(capsensitive("Pgetpgrp")) NAME Pgetpgrp - get the current process group number SYNOPSIS WORD Pgetpgrp(void); DESCRIPTION Pgetpgrp returns the process group number of the currently running process. Process groups are commonly used for job control and other signalling purposes; processes that share the same process group are assumed to be closely related, and are usually stopped all together rather than 1 at a time. SEE ALSO \#Pkill\#, \#Pgetpid\#, \#Psetpgrp\# Last change: Oct. 1, 1991\end screen(capsensitive("Pgetpid")) NAME Pgetpid - get the current process id SYNOPSIS WORD Pgetpid(void); DESCRIPTION Pgetpid returns the process id of the currently running pro- cess. This is a positive 16 bit integer which is unique among all processes currently in the system. The call is always successful. SEE ALSO \#Pgetpgrp\#, \#Pgetppid\# Last change: Oct. 1, 1991\end screen(capsensitive("Pgetppid")) NAME Pgetppid - get the process id for the parent of the current process SYNOPSIS WORD Pgetppid(void); DESCRIPTION Pgetppid returns the process id of the parent of the currently running process. The process id is a positive 16 bit integer. The call is always successful. SEE ALSO \#Pgetpgrp\#, \#Pgetpid\# NOTES If the current process was started directly by the kernel, then Pgetppid will return 0. Last change: Oct. 1, 1991\end screen(capsensitive("Pkill")) NAME Pkill - send a signal to a process SYNOPSIS #include <signal.h> WORD Pkill(WORD pid, WORD sig); DESCRIPTION Pkill sends the signal described by sig to one or more processes, as follows: If pid is a positive number, then the signal is sent to the process with that process id. If pid is 0, the signal is sent to all members of the pro- cess group of the calling process (i.e. all processes which have the same process group number). This includes, of course, the calling process itself. If pid is less than 0, the signal is sent to all processes with process group number -pid. RETURNS 0 if successful. Note that if the current process is a reci- pient of the signal, the Pkill call may not return at all if the process is killed. ERANGE if sig is not a valid signal. EFILNF if pid > 0 and the indicated process has terminated or does not exist, or if pid < 0 and there are no processes in the corresponding process group. EACCDN if pid > 0, the sending process does not have an effective user id of 0, and the recipient process has a dif- ferent user id from the sending process. SEE ALSO \#Psetpgrp\#, \#Psignal\# BUGS The user id checks should also be performed when sending signals to process groups. Do not rely on the lack of checks, as this will be corrected at some point. Last change: Oct. 1, 1991\end screen(capsensitive("Pmsg")) NAME Pmsg - send and receive brief messages SYNOPSIS struct msg { LONG msg1, msg2; WORD pid; }; LONG Pmsg(WORD mode, LONG mboxid, struct msg *msgptr); DESCRIPTION Pmsg sends or receives a message to a specified message box. What sort of operation is performed depends on the bits in mode as follows: Mode Operation 0x0000 read 0x0001 write 0x0002 write, then read from mboxid 0xFFFFxxxx where xxxx is the process id of the current process 0x8000 OR with this bit to make the operation non-blocking. The messages are five words long: two longs and a short, in that order. The values of the first two longs are totally up to the processes in question. The value of the short is the PID of the sender. On return from writes, the short is the PID of the process that read your message. On return from reads, it's the PID of the writer. If the 0x8000 bit is set in the mode, and there is not a reader/writer for the mboxid already, this call returns -1. Otherwise, a read operation waits until a message is written and a write operation waits for a reader to receive the mes- sage. In mode 2, the writer is declaring that it wants to wait for a reply to the message. What happens is that the reader gets put on the ready queue, but the writer is atomically turned into a reader on a mailbox whose mboxid is (0xFFFF0000 | pid). The idea is that this process will sleep until awoken at a later time by the process that read the message. The process reading the original request is guaranteed not to block when writing the reply. RETURNS 0 if successful -1 if bit 0x8000 is set and the Pmsg call would have to block EINVFN if mode is invalid USAGE Used for short messages and as a way to do rendezvous and interprocess communication with little overhead. For more complicated messages or more general IPC, use FIFOs or pseudo-terminals. BUGS There is no provision for a timeout. No checking is done for deadlocks. A deadlock could arise in the following way: Say PID 33 writes in mode 2 to a message box and it blocks. Then somebody writes to PD33 (i.e. mes- sage box (0xFFFF0000 | 33) ) and blocks because you're not waiting for it. Then your write is satisfied, so you become a reader on PD33. We should check to see if there are any writers on PD33 and satisfy that rendezvous! But this could go on forever, and it's easier to stop here. So you lose: this situation is timing sensitive. It shouldn't come up anyway. AUTHOR Allan K. Pratt Last change: Oct. 1, 1991\end screen(capsensitive("Pnice")) NAME Pnice - change process priority for the current process SYNOPSIS WORD Pnice(WORD delta); DESCRIPTION Pnice changes the base process niceness for the current pro- cess by the amount delta. Higher levels of niceness correspond to decreased priority in scheduling, so positive values for delta cause the corresponding process to be scheduled less often. Conversely, negative values for delta cause the process priority to be increased. RETURNS The (adjusted) process priority, as a 16 bit signed integer. 0 is the default priority; values greater than 0 are for higher priority processes (ones that are scheduled more often), and values less than 0 are lower priority processes. SEE ALSO \#Prenice\# BUGS The scheduling algorithm is pretty weird, so it's hard to predict exactly what effect process priorities have. Last change: Oct. 1, 1991\end screen(capsensitive("Prenice")) NAME Prenice - change process priority SYNOPSIS LONG Prenice(WORD pid, WORD delta); DESCRIPTION Prenice changes the base process niceness for process pid by the amount delta. Higher levels of niceness correspond to decreased priority in scheduling, so positive values for delta cause the corresponding process to be scheduled less often. Conversely, negative values for delta cause the pro- cess priority to be increased. RETURNS The current priority for the process, if successful. This is a 16 bit signed quantity. The default priority is 0; higher priority processes have larger priority values, lower prior- ity ones have smaller values. EFILNF if the indicated process does not exist (note that since this is a 32 bit negative number it can be dis- tinguished from the WORD negative numbers returned for low priority processes) EACCDN if the process has a different user id SEE ALSO \#Pnice\# BUGS The scheduling algorithm is pretty weird, so it's hard to predict exactly what effect process priorities have. Last change: Oct. 1, 1991\end screen(capsensitive("Prusage")) NAME Prusage - get resource usage information SYNOPSIS void Prusage(LONG *r); DESCRIPTION Prusage puts information on resources used by the process into the memory pointed to by r, as follows: r[0]: time spent by process in MiNT kernel r[1]: time spent by process in its own code r[2]: total kernel time spent by children of this process r[3]: total user code time spent by children of this process r[4]: memory allocated to this process (bytes) r[5]-r[7]: reserved for future use All times are in milliseconds. SEE ALSO \#Psetlimit\# Last change: Oct. 1, 1991\end screen(capsensitive("Psemaphore")) NAME Psemaphore - create / use / destroy a sempahore SYNOPSIS LONG Psemaphore(WORD mode, LONG id, long timeout); DESCRIPTION Psemaphore is a call that implements uncounted semaphores. A semaphore is used for mutual exclusion: only one process at a time may "own" a given semaphore. For example, a semaphore may be used to protect access to data structures which are in shared memory and which are used by multiple threads in a process: before using the memory a thread must gain ownership of the guarding sema- phore, and when finished the thread must release the sema- phore. The semaphore would be created during initialization and destroyed during shutdown. Semaphores are identified by an id, which is an arbitrary longword. This is the semaphore's "name." The id used to create the semaphore is the "name" of that semaphore from then on. When using semaphores, you should strive to use a longword that is unique. Using four ASCII characters which spell out something is common: 0x4b4f444f ("MODM") for instance might be the id of a semaphore that controls access to a modem. (Actually, this would be a poor choice, since there can be more than one modem in a system and this sema- phore ID isn't flexible enough to handle that. "MDM1" might be better.) Semaphore id's beginning with 0x5f (the underscore charac- ter) are reserved for operating system use. The timeout argument is only used in Mode 2. It is ignored in other modes. A timeout of zero means "return immedi- ately." A value of -1 means "forever" - that is, never time out. Other values are a number of milliseconds to wait for the semaphore before timing out. The mode argument is used to tell what operation the caller desires: MODE ACTION 0 Create and "get" a semaphore with the given ID. 1 Destroy the indicated semaphore. The caller must own the semaphore prior to making this call. 2 Request ownership of the semaphore. Blocks until the semaphore is free or until the timeout expires. See below. 3 Release the semaphore. The caller must own the sema- phore prior to making this call. RETURNS CODE MEANING 0 Success. ERROR A request for a semaphore which the caller already owns. ERANGE The semaphore does not exist. EACCDN Failure. The semaphore already exists (mode 0), you don't own it (modes 1 and 3), or the request timed out (mode 2). NOTES When you create a semaphore you also own it, so you must release it before anybody else can get it. If you are blocked waiting for a semaphore (mode 2 before the timeout expires) and somebody destroys the semaphore, the call will return ERANGE to you (because the requested semaphore does not exist any more!). When a process terminates, any semaphores it owns are released. At most one process may own a semaphore. Ownership is not inherited by children (fork()) or across exec(). Once created, semaphores are never destroyed except upon request. Thus if a program creates a semaphore and then crashes the semaphore will never go away. Semaphores can be implemented using named pipes and file locking. Technically, then, semaphores are redundant. The facility is included as a kernel call because it was deemed necessary to have this kind of exclusion available with lit- tle persistent state or system-call overhead. Last change: Jan. 6, 1992\end screen(capsensitive("Psetuid"), capsensitive("Psetgid")) NAME Psetuid, Psetgid - change a process' user or group id SYNOPSIS WORD Psetuid(WORD uid); WORD Psetgid(WORD gid); DESCRIPTION Psetuid sets the user id of the current process to uid, which must be a number between 0 and 255 inclusive. This function call will fail if the user id is not already 0, so once a process' user id is set it is fixed. Psetuid returns uid, if the call is successful, and EACCDN if the process does not have the authority to change its own user id (i.e. if its effective user id is not 0 at the time of the call). Similarly, Psetgid sets the group id of the current process to gid, which again must be between 0 and 255. The new group id gid is returned if successful, and EACCDN is returned if permission to change groups is denied. SEE ALSO \#Pgetuid\#, \#Pgetgid\# BUGS Security in MiNT is a joke; don't rely on these calls to actually protect you from anything, it's more for informa- tional purposes. Last change: Oct. 1, 1991\end screen(capsensitive("Psetlimit")) NAME Psetlimit - get or set limits on use of system resources SYNOPSIS LONG Psetlimit(WORD lim, LONG value); DESCRIPTION Psetlimit gets or sets a resource limit for a process. Which limit is affected is governed by the value of lim, as fol- lows: 1: get/set maximum CPU time for process (in milliseconds) 2: get/set total maximum memory allowed for process 3: get/set limit on Malloc'd memory for process If value is negative, the limit is unchanged; if value is 0, the corresponding resource is unlimited; otherwise, the resource limit is set to value. Setting the "maximum memory" limit means the process is not allowed to grow bigger than that size overall. Setting the "maximum Malloc'ed" limit means that the process may allo- cate no more than that much memory. The difference is that the latter limit applies above and beyond the text+data+bss size of the process. Using Psetlimit sets the corresponding limit for both the process and any children it creates thereafter. Note that the limits apply to each process individually; setting the child CPU limit value to 1000 and then using \#Pfork\# to create three children results in each of those children get- ting a CPU limit value of one second. They do not have a collective or sum total limit of one second. There is no restriction on increasing a limit. Any process may set any of its limits or its childrens' limits to a value greater than its current limit, or even to zero (unlimited). Memory limits do not apply during execution of \#Pexec\#; that is, if a process is limited to (say) 256KB of memory, it can still exec a child which uses more. Memory limits are not retroactive: if a process owns 256KB of memory and then calls Psetlimit to restrict itself to 128KB, it will not be terminated, but no \#Malloc\# calls will succeed until its size drops below 128KB. CPU limits are retroactive, however: if a process has used three CPU seconds and calls Psetlimit to restrict itself to one second, it will immediately receive SIGXCPU and ter- minate. RETURNS The old limit (0 if there was no limit). BUGS Since the limit applies to the process and its children, you can't limit a child to, say, one millisecond of CPU time: the parent must necessarily limit itself before creating the child, and if it has used more than a millisecond itself, it will die with SIGXCPU. A new set of lim arguments is needed that apply to the caller's future children without applying to the caller. To alleviate this, the parent must create a child process via Pvfork, and this process (which hasn't consumed any CPU time yet) must call Psetlimit and then \#Pexec\# to create the child that is meant to be limited. SEE ALSO \#Prusage\# Last change: Oct. 1, 1991\end screen(capsensitive("Psetpgrp")) NAME Psetpgrp - set the process group number for a process SYNOPSIS LONG Pgetpgrp(WORD pid, WORD neewgrp); DESCRIPTION Psetpgrp sets the process group of the process with process id pid to the number newgrp. The process must have the same user id as the current process, or must be a child of that process. If pid is 0, the process group of the current pro- cess is set. If newgrp is 0, then the process group is set equal to the process id of the process. RETURNS The new process group number, if successful. EFILNF if process pid does not exist. EACCDN if the process with id pid has a different user id and is not a child of the calling process. SEE ALSO \#Pkill\#, \#Pgetpgrp\#, \#Pgetpid\# Last change: Oct. 1, 1991\end screen(capsensitive("Psigaction")) NAME Psigaction - change the way a signal is handled SYNOPSIS #include <signal.h> LONG Psigaction(WORD sig, struct sigaction *act, struct sigaction *oact); DESCRIPTION Psigaction changes the handling of the signal indicated by sig (which must be between 1 and 31; symbolic constants for symbols are defined in the file signal.h). If act is non-zero, then it is assumed to point to a structure describing the signal handling behavior. This structure has the following members: struct sigaction { LONG sa_handler; LONG sa_mask; WORD sa_flags; } If sa_handler is SIG_DFL, then the default action for the signal will occur when the signal is delivered to the process. If sa_handler is SIG_IGN, then the signal will be ignored by the process, and delivery of the signal will have no noticeable effect (in particular, the signal will not interrupt the \#Pause\# or \#Psigpause\# system calls). If the signal is pending at the time of the \#Psignal\# call, it is discarded. If sa_handler is some other value, it is assumed to be the address of a user function that will be called when the signal is delivered to the process. The user function is called with a single LONG argument on the stack, which is the number of the signal being delivered (this is done so that processes may use the same handler for a number of different signals). While the signal is being handled, it is blocked from delivery; thus, signal handling is "reliable" (unlike Version 7 and early System V Unix implementations, in which delivery of a second signal while it was being handled could kill the process). The set of signals specified in sa_mask are also blocked from delivery while the signal handler is executing. Note that, unlike in some versions of Unix, the signal handling is not reset to the default action before the handler is called; it remains set to the given signal handler. The signal handler must either return (via a normal 680x0 rts instruction) or call the \#Psigreturn\# system call to indicate when signal handling is complete; in both cases, the signal will be unblocked. \#Psigreturn\# also performs some internal clean-up of the kernel stack that is necessary if the signal handler is not planning to return (for example, if the C longjmp() function is to be used to continue execution at another point in the program). Signal handlers may make any GEMDOS, BIOS, or XBIOS system calls freely. GEM AES and VDI calls should not be made in a signal handler. The sa_flags field specifies additional, signal-specific signal handling behavior. If sig is SIGCHLD, and the SA_NOCLDSTOP bit is set in sa_flags, then the SIGCHLD signal is sent to this process only when one of its children terminates (and not when a child is suspended by a job control signal). The oact argument to Psigaction, if non-zero, specifies a structure that will be set to reflect the signal handling for sig that was current at the time of the Psigaction system call. Note that calling Psigaction to change behavior of a signal has the side effect of unmasking that signal, so that delivery is possible. This is done so that processes may, while handling a signal, reset the behavior and send themselves another instance of the signal, for example in order to suspend themselves while handling a job control signal. Signal handling is preserved across \#Pfork\# and \#Pvfork\# calls. Signals that are ignored by the parent are also ignored by the child after a \#Pexec\# call; signals that were being caught for handling in a function are reset in the child to the default behavior. RETURNS 0 on success ERANGE if sig is not a legal signal. EACCDN if the signal may not be caught by the user SEE ALSO \#Pkill\#, \#Psigblock\#, \#Psignal\#, \#Psigreturn\# BUGS Signal handling can be nested only a small (around 3) number of times, i.e. if 4 signals are delivered to a process, and the process has established handlers for all 4, and none of the handlers has returned or called \#Psigreturn\#, then there is a very good chance of a stack overflow killing the process off. In practice, this is unlikely to happen. AUTHOR Alex Kiernan Last change: May 1, 1992\end screen(capsensitive("Psigblock"), capsensitive("Psigsetmask")) NAME Psigblock, Psigsetmask - block or unblock delivery of sig- nals SYNOPSIS LONG Psigblock(LONG mask); LONG Psigsetmask(LONG mask); DESCRIPTION Psigblock adds the set of signals defined by the variable mask to the set of signals which are blocked from delivery. Each bit of mask represents a signal; if bit n of mask is set, then signal number n is blocked. Psigblock returns the set of blocked signals as it was prior to the new signals being added to it; the old set can thus be restored with the Psigsetmask call. Psigsetmask replaces the set of blocked signals with the set in mask; the bits of mask have the same meaning as they do for Psigblock, except that bits that are set to 0 will cause the corresponding signals to no longer be blocked. Psigset- mask returns the old set of blocked signals. Note that certain signals (e.g. SIGKILL) cannot be blocked, and the kernel will (silently) clear the corresponding bits in mask before changing the blocked signal set. Blocked signals remain blocked across \#Pfork\# and \#Pvfork\# calls. After a \#Pexec\# call, the child process will always start with an empty set of blocked signals, regardless of which signals were blocked by the parent. SEE ALSO \#Pkill\#, \#Psignal\#, \#Psigpending\# Last change: Oct. 1, 1991\end screen(capsensitive("Psignal")) NAME Psignal - change the way a signal is handled SYNOPSIS #include <signal.h> LONG Psignal(WORD sig, LONG handler); DESCRIPTION Psignal changes the handling of the signal indicated by sig (which must be between 1 and 31; symbolic constants for sym- bols are defined in the file signal.h). The new signal handler applies to this process only. If handler is SIG_DFL, then the default action for the sig- nal will occur when the signal is delivered to the process. If handler is SIG_IGN, then the signal will be ignored by the process, and delivery of the signal will have no notice- able effect (in particular, the signal will not interrupt the \#Pause\# system call). If the signal is pending at the time of the Psignal call, it is discarded. If handler is some other value, it is assumed to be the address of a user function that will be called when the sig- nal is delivered to the process. The user function is called with a single LONG argument on the stack, which is the number of the signal being delivered (this is done so that processes may use the same handler for a number of different signals). While the signal is being handled, it is blocked from delivery; thus, signal handling is "reliable" (unlike Version 7 and early System V Unix implementations, in which delivery of a second signal while it was being handled could kill the process). Also note that, unlike some versions of Unix, the signal handling is not reset to the default action before the handler is called; it remains set to the given signal handler. The signal handler must either return (via a normal 680x0 rts instruction) or call the Psigreturn system call to indi- cate when signal handling is complete; in both cases, the signal will be unblocked. Psigreturn also performs some internal clean-up of the kernel stack that is necessary if the signal handler is not planning to return (for example, if the C longjmp() function is to be used to continue execu- tion at another point in the program). Signal handlers may make any GEMDOS, BIOS, or XBIOS system calls freely. GEM AES and VDI calls should not be made in a signal handler. Note that calling Psignal to change behavior of a signal has the side effect of unmasking that signal, so that delivery is possible. This is done so that processes may, while han- dling a signal, reset the behavior and send themselves another instance of the signal, for example in order to suspend themselves while handling a job control signal. Signal handling is preserved across \#Pfork\# and \#Pvfork\# calls. Signals that are ignored by the parent are also ignored by the child after a \#Pexec\# call; signals that were being caught for handling in a function are reset in the child to the default behavior. RETURNS The old value of the signal handler on success; this will be either SIG_DFL, SIG_IGN, or a function address. ERANGE if sig is not a legal signal. EACCDN if the signal may not be caught by the user SEE ALSO \#Pkill\#, \#Psigaction\#, \#Psigblock\#, \#Psigreturn\# BUGS Signal handling can be nested only a small (around 3) number of times, i.e. if 4 signals are delivered to a process, and the process has established handlers for all 4, and none of the handlers has returned or called Psigreturn, the there is a very good chance of a stack overflow killing the process off. In practice, this is unlikely to happen. Last change: May 1, 1992\end screen(capsensitive("Psigpause")) NAME Psigpause - suspend process until a signal is received SYNOPSIS void Psigpause(LONG mask); DESCRIPTION Psigpause sets a new signal mask and then causes the calling process to go to sleep until a signal that is not being ignored or masked is received. If a signal handler has been established for that signal with the \#Psignal\# system call, then the handler is invoked before Psigpause returns; if the handler does a longjmp to a different point in the program, if it exits the program, or if the signal handler was set to SIG_DFL and the default action for the signal is to terminate the process, then Psigpause will never return. If Psigpause does return, then the signal mask is restored to what it was prior to the Psigpause system call, i.e. the new signal mask specified by mask is only temporary. SEE ALSO \#Pause\#, \#Psigblock\#, \#Psignal\#, \#Psigsetmask\# BUGS If a signal handler doesn't return (for example, because it uses longjmp) then the signal mask is left set to mask. AUTHOR Alex Kiernan Last change: May 1, 1992\end screen(capsensitive("Psigpending")) NAME Psigpending - determine which signals have been sent but not delivered SYNOPSIS LONG Psigpending(void); DESCRIPTION Psigpending returns a bit mask containing the signals that have been sent to the calling process but not yet delivered (probably because they have blocked, either directly via Psigblock or Psigsetmask, or indirectly because of signal handling. RETURNS Bit n of the returned value is set if (and only if) signal number n is pending. SEE ALSO \#Psigblock\#, \#Psignal\#, \#Psigsetmask\# Last change: Oct. 1, 1991\end screen(capsensitive("Psigreturn")) NAME Psigreturn - exit from a signal handler SYNOPSIS void Psigreturn(void); DESCRIPTION Psigreturn is used to prepare to exit from a signal handler. This is done automatically by the kernel when a signal handler returns, so it is needed only before a program uses the C longjmp function (or some similar facility) to do a non-local jump. Psigreturn will fail (harmlessly) if no signal is being processed at the time it is called. Note that the MiNT library longjmp function already contains a call to Psigreturn, so if you're using that library you don't need to worry about this. SEE ALSO \#Psignal\# BUGS Calling Psigreturn from a signal handler, and then actually returning from that handler, is likely to produce extremely unpleasant results. Last change: Oct. 1, 1991\end screen(capsensitive("Pumask")) NAME Pumask - set file and directory creation mask SYNOPSIS WORD Pumask(WORD mode); DESCRIPTION Pumask changes the file and directory creation mask of the current process to the unsigned 16 bit quantity specified in mode. The old value of the creation mask is returned. Child processes inherit the new value for the mask. When a new file is created with Fcreate or a new directory created with \#Dcreate\# the initial access permissions (see \#Fchmod\# for a description of these) for the newly created file or directory are normally set so that all permissions are granted (except that execute permission is not normally granted for files). The creation mask set by Pumask deter- mines which permissions are not to be granted by default. Thus, files created after a Pumask(S_IWOTH|S_IWGRP|S_IXOTH) call will be readable by anyone, but writable only by the owner; moreover, directories created after this call would be searchable by the owner and members of the same group, but not by anyone else. SEE ALSO \#Dcreate\#, \#Fchmod\#, \#Fcreate\# BUGS Pumask doesn't affect explicit Fchmod calls, as some might expect. Last change: Oct. 1, 1991\end screen(capsensitive("Pusrval")) NAME Pusrval - get or set process specific information SYNOPSIS LONG Pusrval(LONG val); DESCRIPTION Pusrval may be used to set or retrieve the old process specific user value. This is a long word which is attached to the process, and is inherited by child processes. The use and meaning of the value is entirely up to applications; the kernel only records it. If val is -1 no change is made to the user value; otherwise it is set to val. RETURNS The old process specific user value. BUGS -1 cannot be used as a user value. Last change: Oct. 1, 1991\end screen(capsensitive("Pvfork")) NAME Pvfork - create a copy of the current process SYNOPSIS WORD Pvfork(void); DESCRIPTION Pvfork creates a copy of the current process. Both the child (the new process created) and the parent (the process which first made the call) share the same address space, i.e. any changes that the child makes to variables will also be noticed by the parent. The new process begins execution with an apparent return from the Pvfork call. Because the two processes share the same address space, including the same stack, there could be many problems if they actually were running at the same time. Therefore, the parent process is suspended until the child process either exits or uses mode 200 of \#Pexec\# to overlay itself with a new program in a new address space. RETURNS 0 in the child The new process id (a positive number), in the parent. ENSMEM if there is not enough memory to create the new pro- cess. SEE ALSO \#Pexec\#, \#Pfork\# BUGS If the parent is in supervisor mode when this call is made, the child will be started in user mode anyway; thus, it is strongly recommended that this call be made only from user mode. Last change: Oct. 1, 1991\end screen(capsensitive("Pwait"), capsensitive("Pwait3")) NAME Pwait, Pwait3 - get exit status of children SYNOPSIS LONG Pwait(void); LONG Pwait3(WORD flag, LONG *rusage); DESCRIPTION Pwait3 attempts to determine the exit code for any stopped children or children that have terminated. If bit 1 of flag is set, then children that are stopped due to job control are reported; otherwise only children that have actually terminated are reported. A stopped process will be reported at most once (unless it is re-started and stopped again); similarly a terminated process will be reported only once. If the process does have children, but none are currently stopped or terminated and not yet waited for, then the behavior of Pwait3 is controlled by bit 0 of flag. If it is clear, the function will wait until some child is stopped or terminates; if it is set, the function will return immedi- ately. The rusage parameter, if non-zero, should point to two long words, into which information about the child's CPU time usage is placed, as follows: rusage[0]: milliseconds spent by child in user space rusage[1]: milliseconds spent by child in kernel space The Pwait() system call is equivalent to Pwait3(2,(LONG*)0), and is provided both for convenience and for backward compatibility. RETURNS If a child process is found, its process id is placed in the upper 16 bits of the 32 bit value returned, and its exit status (as passed to \#Pterm\# or \#Ptermres\#, as determined impli- citly by \#Pterm0\#, or as determined by the type of signal that stopped or killed the process) is placed in the lower 16 bits. If the process was stopped or terminated by signal n, then its exit status will be ( n << 8 ) | x. where x is 127 if the process was stopped and 0 if the process was ter- minated. 0 if bit 0 of flag is set and the Pwait3 system call would have otherwise blocked waiting for a child to exit or stop. EFILNF if no unwaited for children exist. SEE ALSO \#Pexec\#, \#Pterm\#, \#Pterm0\#, \#Ptermres\# BUGS It is not possible to wait for a specific child process. Last change: Oct. 1, 1991\end